How to Add A New Command

Sunday, February 19, 2023

12:05 PM

Commands are categorized into functional domains. These domains are described by the folders beneath the Commands folder, for example Clean, Edit, File, Images, etc. When inventing a new command, it's important to identify the proper domain. If this command doesn't fit an existing domain, consider whether it can be added to the Extras domain, the Tools domain, or if is the beginning of multiple related commands, create a new domain folder to contain this and other related commands.

 

📓

Follow the naming conventions

The naming conventions described below are very important for consistency but also critical for commands to fit within the OneMore command framework which dynamically enumerates commands, discovers key bindings, and enables other mechanisms that streamline adding a new command.

 

To add a new command to OneMore

 

  1. Add a new class file in the appropriate Commands\domain folder.
    1. Name the class using form nameCommand such as TrimCommand
    2. The file name should match the class name such as TrimCommand.cs.

 

  1. Keep the namespace as River.OneMoreAddIn.Commands
  2. Derive the class from the Command base class and declare it as internal
  3. Add a public constructor, even if its body is blank
  4. Override the Command.Execute method

 

Example:

 

namespace River.OneMoreAddIn.Commands

{

    internal class TrimCommand : Command

    {

        public TrimCommand()

        {

        }

 

        public override async Task Execute(params object[] args)

        {

        }

    }

}

 

  1. Add a new method to the AddinCommands.cs file to invoke the command

 

  1. The name should be derived from the class, replacing Command with Cmd such as TrimCmd
  2. It must be declared async and accept an IRibbonControl parameter
  3. It must invoke the command using factory.Run as shown here

 

[Command("ribTrimButton_Label", Keys.None, "ribCleanMenu")]

public async Task TrimCmd(IRibbonControl control)

=> await factory.Run<TrimCommand>(false);

 

  1. The CommandAttribute first parameter specifies the resource ID used to translate the name of the command. This must be named using the form ribNameButton_Label
  2. The second parameter defines the default key binding; set to Keys.None to indicate to binding
  3. The third parameter names the functional domain (for future use)

 

  1. Add a button control or menu item to the Ribbon\Ribbon.xml file

 

  1. Specify a unique id and label property. The id should match the CommandAttribute resource name with the _Label part, for example ribTrimButton
  2. Choose an appropriate imageMso name from imageMso List
  3. Set the onAction property to the nameCmd method added to AddInCommands.cs

 

<button

  id="ribTrimButton"

  imageMso="AutoTextGallery"

  getLabel="GetRibbonLabel"

  onAction="TrimCmd"/>

 

 

#omwiki #omdeveloper

 

© 2020 Steven M Cohn. All rights reserved.

Please consider a sponsorship or one-time donation to support ongoing development

 

Created with OneNote.